Overview
Composer is a
simple but powerful CMS based on [Pandoc], [Bootstrap] and [GNU Make].
It is a document and website build system that processes directories or
individual files in [Markdown] format.
Traditionally, CMS stands for Content Management System. Composer is designed to be a
Content Make System. Written content is vastly easier to manage
as plain text, which can be crafted with simple editors and tracked with
revision control. However, professional documentation, publications, and
websites require formatting that is dynamic and feature-rich.
[Pandoc] is an extremely powerful document conversion tool, and is a widely
used standard for processing [Markdown] into other formats. While it has
reasonable defaults, there are a large number of options, and additional tools
are required for some formats and features.
Composer consolidates
all the necessary components, simplifies the options, and prettifies the output
formats, all in one place. It also serves as a build system, so that large
repositories can be managed as documentation archives or published as [Bootstrap
Websites].
![Composer Screenshot]()
Quick Start
Use make help to get started:
make [-f .../Makefile] [variables] <filename>.<extension>
make [-f .../Makefile] [variables] <target>
Fetch the necessary binary components (see Requirements):
make _update-all
Create documents from source [Markdown] files (see Formatting Variables):
make README.html
make Composer-v3.0.Manual.html c_list="README.md LICENSE.md"
Save a persistent configuration (see [Recommended Workflow], [Configuration
Settings] and Special Targets):
make template >.composer.mk
$EDITOR .composer.mk
book-Composer-v3.0.Manual.html: README.md LICENSE.md
make clean
make all
Recursively install and build an entire directory tree (see [Recommended
Workflow]):
cd .../documents
mv .../composer .Composer
make -f .Composer/Makefile install-all
make all-all
See help-all for full details and additional targets.
Principles
The guiding principles of Composer:
- All source files in readable plain text
- Professional output, suitable for publication
- Minimal dependencies, and entirely command-line driven
- Separate content and formatting; writing and publishing are independent
- Inheritance and dependencies; global, tree, directory and file
overrides
- Fast; both to initiate commands and for processing to complete
Direct support for key document types (see [Document Formatting]):
- [HTML] & [Bootstrap Websites]
- [PDF]
- [EPUB]
- [Reveal.js Presentations]
- [Microsoft Word & PowerPoint]
Requirements
Composer has almost no
external dependencies. All needed components are integrated, including [Pandoc].
The repository needs to be initialized with [_update-all] to fetch the [Pandoc]
and [YQ] binaries (see [Repository Versions]).
Composer does require a
minimal command-line environment based on [GNU] tools, particularly [GNU Make],
which is standard for all [GNU/Linux] systems. The [Windows Subsystem for Linux]
for Windows and [MacPorts] for macOS both provide suitable environments.
The one large external requirement is [TeX Live], and it can be installed
using the package managers of each of the above systems. It is only necessary
for creating [PDF] files.
Below are the versions of the components in the repository, and the tested
versions of external tools for this iteration of Composer. Use [check] to
validate your system.
| [Pandoc] |
2.18 |
GPL |
| [YQ] |
v4.24.2 |
MIT |
| [Bootstrap] |
v5.1.3 |
MIT |
| [Markdown Viewer] |
059f3192d4ebf5fa9776 |
MIT |
| [Reveal.js] |
4.3.1 |
MIT |
| GNU Bash |
5.0.18 |
| - GNU Coreutils |
8.31 |
| - GNU Findutils |
4.8.0 |
| - GNU Sed |
4.8 |
| [GNU Make] |
4.2.1 |
| - [Pandoc] |
2.18 |
| - [YQ] |
4.24.2 |
| - [TeX Live] (pdf) |
2021 3.14159 2.6-1.40.22 |
[Markdown Viewer] is included both for its CSS stylesheets, and for real-time
rendering of [Markdown] files as they are being written. To install, follow the
instructions in the README.md, and select the appropriate
manifest.*.json file for your browser.
The versions of the integrated repositories can be changed, if desired (see
[Repository Versions]).
Command Examples
Fetch the necessary binary components (see Requirements):
make _update-all
Create documents from source [Markdown] files (see Formatting Variables):
make README.html
make Composer-v3.0.Manual.html c_list="README.md LICENSE.md"
Save a persistent configuration (see [Recommended Workflow], [Configuration
Settings] and Special Targets):
make template >.composer.mk
$EDITOR .composer.mk
book-Composer-v3.0.Manual.html: README.md LICENSE.md
make clean
make all
Recursively install and build an entire directory tree (see [Recommended
Workflow]):
cd .../documents
mv .../composer .Composer
make -f .Composer/Makefile install-all
make all-all
See help-all for full details and additional targets.